<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Ant-contrib Tasks: Trycatch</title>
  </head>

  <body>
    <h1>Trycatch</h1>

    <p>A wrapper that lets you run a set of tasks and optionally run a
    different set of tasks if the first set fails and yet another set
    after the first one has finished.</p>

    <p>This mirrors Java's try/catch/finally.</p>

    <p>The tasks inside of the required <code>&lt;try&gt;</code>
    element will be run.  If one of them should throw a BuildException
    several things can happen:</p>

    <ul>
      <li>If there is no <code>&lt;catch&gt;</code> block, the
      exception will be passed through to Ant.</li>

      <li>If the property attribute has been set, a property of the
      given name will be set to the message of the exception.</li>

      <li>If the reference attribute has been set, a reference of the
      given id will be created and point to the exception object.</li>

      <li>If there is a <code>&lt;catch&gt;</code> block, the tasks
      nested into it will be run.</li>
    </ul>

    <p>If a <code>&lt;finally&gt;</code> block is present, the task
    nested into it will be run, no matter whether the first tasks have
    thrown an exception or not.</p>

    <h2>Parameters</h2>
    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">property</td>
        <td valign="top">Name of a property that will receive the
        message of the exception that has been caught (if any)</td>
        <td align="center" valign="top">No.</td>
      </tr>
      <tr>
        <td valign="top">reference</td>
        <td valign="top">Id of a reference that will point to the
        exception object that has been caught (if any)</td>
        <td align="center" valign="top">No</td>
      </tr>
    </table>

    <h2>Example</h2>

<pre>
&lt;trycatch property=&quot;foo&quot; reference=&quot;bar&quot;&gt;
  &lt;try&gt;
    &lt;fail&gt;Tada!&lt;/fail&gt;
  &lt;/try&gt;

  &lt;catch&gt;
    &lt;echo&gt;In &amp;lt;catch&amp;gt;.&lt;/echo&gt;
  &lt;/catch&gt;

  &lt;finally&gt;
    &lt;echo&gt;In &amp;lt;finally&amp;gt;.&lt;/echo&gt;
  &lt;/finally&gt;
&lt;/trycatch&gt;

&lt;echo&gt;As property: ${foo}&lt;/echo&gt;
&lt;property name=&quot;baz&quot; refid=&quot;bar&quot; /&gt;
&lt;echo&gt;From reference: ${baz}&lt;/echo&gt;
</pre>

    <p>results in</p>

<pre>
  [trycatch] Caught exception: Tada!
      [echo] In &lt;catch&gt;.
      [echo] In &lt;finally&gt;.
      [echo] As property: Tada!
      [echo] From reference: Tada!
</pre>

    <hr>
    <p align="center">Copyright &copy; 2002-2003 Ant-Contrib Project. All
    rights Reserved.</p>

  </body>
</html>
